home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / wx_lib10.zoo / wx_lib.doc < prev    next >
Encoding:
Text File  |  1992-08-02  |  8.6 KB  |  252 lines
  1.                     wx_lib 1.0 documentation
  2.  
  3.     Code and text, Copyright 1992, Michael Alan Dorman.
  4.  
  5.     Contacting me:
  6.  
  7. M.DORMAN2 on GEnie.
  8. mad@sss.cba.ua.edu on the Internet.
  9.  
  10. Contact me if you have any suggestions or improvements. However,
  11. I've spent a lot of time making this thing work with at least
  12. two compilers, and I won't really consider any sort of hacks
  13. that are terribly compiler specific.  I also won't consider
  14. hacks that will make it break on future versions of TOS/GEM.  If
  15. you feel that your change must make it to the public, you're
  16. welcome to release it, but credit me as the original author, and
  17. NAME IT SOMETHING ELSE.
  18.  
  19.     Just for the litigious pedants:
  20.  
  21. I make no warranty as to the correct operation of this library,
  22. and will not be liable for damage that occurs from the use or
  23. misuse of it.
  24.  
  25.     What you're reading:
  26.  
  27. This is the documentation for the Extended Window Library I'm
  28. working on.  It's being written as the library is forming up, so
  29. it's going to be pretty hectic.  I imagine it'll get edited a
  30. lot as I go along, and probably need more than it gets.
  31.  
  32. The source to the library is included.  Don't feel hesitant to
  33. examine it.  None of it's very sophisticated.
  34.  
  35. One caveat:  The library almost needs its own VDI workstation. 
  36. If you don't use a workstation for anything other than this
  37. library, you're fine.  If you don't change the fill color, the
  38. fill pattern, or the text color or alignment, you don't need
  39. another workstation.  If you change any of the above, you do,
  40. because in order to speed things up, I went ahead and decided
  41. that the library wouldn't have to re-set things in a million
  42. different places just to be careful.  Thus, all the settings are
  43. made in the wx_init() call, and they're assumed to stay valid
  44. from there on out.  If you change them, well, you'll have to be
  45. sure to change them back before you make any wx_lib calls.
  46.  
  47.     Usage:
  48.  
  49. I've gotten this thing to compile and run using both GCC 2.1 and
  50. the GNU-crew's GEM libraries, and HSC 1.40 with GemFast 1.8.  It
  51. should work fine with HSC 1.33i and GemFast 1.7, though I
  52. haven't tested it.  I've included a wx_lib.a file for HSC 1.40,
  53. and a wx_lib.olb for GCC 2.1.
  54.  
  55. If you find things that need to be, say, #ifdef'd to make it
  56. work with another compiler, please contact me--I want this thing
  57. to be as general as possible.
  58.  
  59. The file wx_tst.c is a test program for the library.  It uses
  60. all of the library functions, at one time or another.  Look at
  61. it.  It's short and to the point.  The files wx_tst_h.prg and
  62. wx_tst_g.prg are two different executables of the exact same
  63. source file, one compiled with HSC 1.40 (_h.prg) and one with
  64. GCC 2.1 (_g.prg).  They both run pretty fast.
  65.  
  66.     Function descriptions:
  67.  
  68. I'm just going to enumerate and describe the individual
  69. functions in alphabetical order, just to make it easy.
  70.  
  71. void        wx_clear(ws)
  72. Window    *ws;
  73.  
  74. This functions clears the interior of the window by drawing a
  75. filled rectangle of the proper size in the window's work space. 
  76. It is, by default, set to be drawn in color 0--the default color
  77. being white on STs.
  78.  
  79. void        wx_close(ws)
  80. Window    *ws;
  81.  
  82. This function closes and deletes the window in question.  It
  83. doesn't reset the parameters of the Window structure, so you can
  84. use it again with another call to wx_open().
  85.  
  86. void        wx_free(ws)
  87. Window    *ws;
  88.  
  89. It occured to me that with GemFast 1.8, you can simply call
  90. apl_vopen() to open a VDI workstation, and that returns the VDI
  91. handle.  Which would allow you, in a perfect world, to just call
  92. wx_init(&ws,apl_vopen(),gl_wchar,gl_hchar).  Thus you'd never
  93. see the VDI handle.  All this function does is close the VDI
  94. workstation that you've assigned to the wx_lib functions,
  95. without having to directly modify any values in the structure.
  96.  
  97. void        wx_fscroll(ws)
  98. Window    *ws;
  99.  
  100. This is a function that is primarily used internally by the
  101. library to scroll the window forward.  It automatically scrolls
  102. the window by the number of lines in the ws->scrl variable.  It
  103. uses a standard vro_cpyfrm() call to do it.
  104.  
  105. void        wx_full(ws)
  106. Window    *ws;
  107.  
  108. This function opens the window to its declared full parameters,
  109. which default to being the size if the full desktop, if the
  110. values aren't changed before the wx_open() call.
  111.  
  112. void        wx_get(ws)
  113. Window    *ws;
  114.  
  115. This function uses the standard wind_get() call to load the
  116. correct values into the various GRECTs in the Window structure.
  117.  
  118. int        wx_info(ws,sp)
  119. Window    *ws;
  120. char        *sp;
  121.  
  122. This allocates sufficient memory to hold the string you pass it,
  123. points the ws->name parameter in that direction, and then uses
  124. wind_set() to point the window at that string.  If you call it
  125. again, it free()'s the original buffer and then allocates a new
  126. one.
  127.  
  128. int        wx_init(ws,vh,gl_wchar,gl_hchar)
  129. Window    *ws;
  130. int        vh,
  131.         gl_wchar,
  132.         gl_hchar;
  133.  
  134. This function sets up some variables that the wx_lib needs from
  135. the system.  The first is the VDI handle, which is placed in the
  136. ws->vdih variable, for easy access.  If it is less than 0, the
  137. routine returns an error.  The other two parameters are from the
  138. graf_handle() call, and represent the height and width of a
  139. character in the system font.  This is necessary for the correct
  140. calculation of the "cursor" position.
  141.  
  142. void        wx_move(ws,x,y)
  143. Window    *ws;
  144. int        x,
  145.         y;
  146.  
  147. This call takes the x and y parameters you pass to it, and use
  148. wind_set() to move the window to that position.  They then
  149. update all the relevant GRECTs in the Window structure.
  150.  
  151. int        wx_name(ws,sp)
  152. Window    *ws;
  153. char        *sp;
  154.  
  155. This function acts exactly like wx_info() except it acts on the
  156. name field of the window, instead of the info field.
  157.  
  158. void        wx_new(ws)
  159. Window    *ws;
  160.  
  161. This is just a utility function that sets the members of ws to
  162. some defaults that wx_open will accept gracefully.
  163.  
  164. int        wx_open(ws)
  165. Window    *ws;
  166.  
  167. This function creates and opens the window that is described in
  168. the Window structure ws.  It updates all relevant GRECTs and
  169. sets the x and y cursor positions to 0.
  170.  
  171. void        wx_outstr(ws,sp)
  172. Window    *ws;
  173. char        *sp;
  174.  
  175. This is the most primitive of the output functions available. 
  176. It prints a string at the current position, with no regard for
  177. whether it is on screen or not.  It updates the x location of
  178. the "cursor", and does nothing else.  It doesn't understand any
  179. special characters like \r, \n, \t, and will probably print them
  180. as their printable counterparts.
  181.  
  182. void        wx_printf(ws,sp,...)
  183. Window    *ws;
  184. char        *sp;
  185.  
  186. This is a windowed version of the old C warhorse, printf().  It
  187. accepts any formatting characters that printf() will.  It
  188. runs the string through vsprintf() and then hands that string to
  189. wx_puts() which knows about things like \n, \r, etc.
  190.  
  191. int        wx_puts(ws,sp)
  192. Window    *ws;
  193. char        *sp;
  194.  
  195. This function is the slightly-less primitive sibling of
  196. wx_outstr() and the slightly more primitive sibling of
  197. wx_printf().  It knows about control chars like \n, \r, \t
  198. (though at this time, it merely "eats" tabs, outputting a single
  199. space in their stead), but doesn't know anything about
  200. sophisticated formatting a la printf().  It does have to
  201. allocate an internal buffer in order to process the string, and
  202. will return FALSE if it is unable to.
  203.  
  204. void        wx_setclip(ws)
  205. Window    *ws;
  206.  
  207. This function sets the clipping rectangle for the VDI
  208. workstation to the current work area of the window in question.
  209.  
  210. void        wx_settype(ws,t)
  211. Window    *ws;
  212. int        t;
  213.  
  214. This is functionally similar to the statement:
  215.  
  216.     ws.type = INFO|MOVER|etc.
  217.  
  218. It is merely here for consistency in calling procedure. 
  219. Eventually I plan to have it so that you have no need to modify
  220. variables in the Window structure directly, thereby making
  221. things a bit more controlled and easy-to-follow.  Obviously, the
  222. value you use should be from whatever your GEM header file is,
  223. ORing together different bit settings.
  224.  
  225. void        wx_size(ws,w,h)
  226. Window    *ws;
  227. int        w,
  228.         h;
  229.  
  230. This function is much like wx_move(), with the caveat that it
  231. sets the window to the width and height provided, rather than
  232. the position.  It updates all necessary variables and GRECTs.
  233.  
  234.     What's coming:
  235.  
  236. That's it for the documentation.  It will be updated, and
  237. become more complete as I add functionality and have time.  In
  238. the mean-time, well, you have the example program, and you have
  239. the library source.  Have at it.
  240.  
  241. I plan to work on this.  I've used it in one program out there
  242. already--BoozGEM.  Actually, that was the previous, slow,
  243. GemFast specific version.  Now it's better, and I'm going to
  244. have to go hack some more.
  245.  
  246. I really do apologize that this is so abrupt, but I've got a lot
  247. to do in the next week, and then I move, so it was this or wait
  248. a couple of weeks to get it out at all.  I chose to get it out
  249. now.
  250.  
  251. Mike Dorman, 02/08/92.
  252.